home *** CD-ROM | disk | FTP | other *** search
/ Aminet 23 / Aminet 23 (1998)(GTI - Schatztruhe)[!][Feb 1998].iso / Aminet / disk / misc / HDOff_1_40.lha / Developers.doc < prev    next >
Text File  |  1997-11-13  |  6KB  |  186 lines
  1.  
  2.                          HDOff - Developer`s Note v1.2
  3.                 © 1997 by Gideon Zenz - all rights reserved
  4.  
  5. INTRODUCTION
  6.  
  7. This  is  my  2nd  try  of  the Developer`s Guide for HDOff.  I hope it`s a
  8. little bit better than the 1st version.  New for this, the port`s structure
  9. is also included in a C-version, and also a C example program.
  10.  
  11. CHANGES
  12.  
  13. I  decided  to  make  some adjustements on the portstructure!  Note the new
  14. field HD_Reserved, and also that there are now NO BYTE fields!  I hope this
  15. makes programming a bit easier.
  16.  
  17. Changes for port 101: (HDOff 1.35)
  18. hd_(Un|%)Subscribe  doesn`t return 0 on failure, but hd_Failure instead (as
  19. 0  ^=  hd_GetStats).   Thx to M.Andree for this.  Cleaned up the cmd`s, now
  20. hd_Die is -1 instead of 0xff.
  21.  
  22. Changes for port 103: (HDOff 1.36)
  23. - HDOff  is   multi-thread  now,  so  your  msg`s  are (nearly) immediately
  24.   processed now!
  25. - A   hd_SetStats  with  0  disables now the HD for HDOff.  A value between
  26.   0<x<60 will be ignored
  27. - New command hd_HDoffVersion
  28.  
  29. Changes for port 104: (HDOff 1.37)
  30. - New command hd_QueryCtrl
  31.  
  32. Changes for port 105: (HDOff 1.40)
  33. - New Option ProModule for hd_QueryCtrl
  34.  
  35. THE PORT
  36.  
  37. HDOff  communicates  with  the  world  using  an exec messageport.  You can
  38. simply  send  messages  to  this  port to get informations about the actual
  39. status  f.e.   of the harddrives or set new parameter and so on.  If you do
  40. not  now how to use such a port, have a look in the RKRM`s and the included
  41. demosource  (GetStats.c).   It is written in C, but you should hopefully be
  42. able to understand this, even if you now little about C.
  43.  
  44. Now the real part:
  45.  
  46. The name of the port is "HDOFF_PORT"
  47.  
  48. Here is the structure for C :
  49.  
  50. NOTE the actual portversion is 105  (standing for 1.05)
  51.  
  52. NOTE also that HD_Reserved must be 0!
  53.  
  54. /****************************************************************************/
  55. /* The message-structure*/
  56.  struct HD {
  57.      struct  Message HD_Msg;
  58.      WORD    HD_Cmd;
  59.      UWORD   HD_TimeHD0;
  60.      UWORD   HD_TimeHD1;
  61.      UWORD   HD_TimeLeftHD0;
  62.      UWORD   HD_TimeLeftHD1;
  63.      BOOL    HD_StatHD0;
  64.      BOOL    HD_StatHD1;
  65.      ULONG   HD_PortVer;
  66.      LONG    HD_Reserved;
  67.      }
  68. /* define HDOff`s commands*/
  69. #define hd_GetStats     0x0
  70. #define hd_SetStats     0x1
  71. #define hd_Subscribe    0x2
  72. #define hd_Unsubscribe  0x3
  73. #define hd_StopDrive    0x4
  74. #define hd_Quit         0x5
  75. #define hd_ForceQuit    0x6
  76. #define hd_HDoffVersion 0x7
  77. #define hd_QueryCtrl    0x8
  78. #define hd_Failure      -2
  79. #define hd_Die          -1
  80. /****************************************************************************/
  81.  
  82. And here the assemblerstructure:
  83.  
  84. /****************************************************************************/
  85.     STRUCTURE       HD,MN_SIZE
  86.         WORD    HD_Cmd
  87.         UWORD   HD_TimeHD0      ;Time in secs (startvalue)
  88.         UWORD   HD_TimeHD1
  89.         UWORD   HD_TimeLeftHD0  ;Time in secs (actual)
  90.         UWORD   HD_TimeLeftHD1
  91.         BOOL    HD_StatHD0      ;$ffff(TRUE): Drive off
  92.         BOOL    HD_StatHD1
  93.         ULONG   HD_PortVer      ;Version of the port
  94.         LONG    HD_Reserved     ;reserved for future use! Set to 0!
  95.         LABEL   HD_SIZE
  96.  
  97. hd_GetStats     equ     $00
  98. hd_SetStats     equ     $01
  99. hd_Subscribe    equ     $02
  100. hd_Unsubscribe  equ     $03
  101. hd_StopDrive    equ     $04
  102. hd_Quit         equ     $05
  103. hd_ForceQuit    equ     $06
  104. hd_HDoffVersion    equ    $07
  105. hd_QueryCtrl    equ     $08
  106. hd_Failure      equ     -2
  107. hd_Die          equ     -1
  108. /****************************************************************************/
  109.  
  110.  
  111. COMMAND DOCUMENTATION
  112.  
  113. hd_GetStats     equ     $00
  114. ~~~~~~~~~~~
  115. This gives you back the message filled with valid values.
  116.  
  117. hd_SetStats     equ     $01
  118. ~~~~~~~~~~~
  119. You  can  set  HD_TimeHD0 and HD_TimeHD1 to new values, and you will get an
  120. answer like hd_GetStats.  This means, you have to initalize HD_TimeHDx with
  121. the  number  of seconds(!) you want and PutMsg() it.  HDOff reset`s now its
  122. internal timecounters to your values.
  123.  
  124. hd_Subscribe    equ     $02
  125. ~~~~~~~~~~~~
  126. If  you  subscribe,  you  will  get  a  message  everytime a drive has been
  127. switched  on/off.  Check the answer!  If HD_Cmd=hd_Failure your subscribing
  128. was unsuccessfull.
  129.  
  130. If  a drive changed its status, you`ll get a messy with HD_Cmd=hd_Subscribe
  131. filled  with the new datas.  You must not change/reply or do something else
  132. with this messy (except reading it out, of course ;) !
  133.  
  134. hd_Unsubscribe  equ     $03
  135. ~~~~~~~~~~~~~~
  136. You   won`t   get  a  messys  on  a  drive  power  down/up  any  more.   If
  137. HD_Cmd=hd_Failure you weren`t subscribed :)
  138.  
  139. hd_StopDrive    equ     $04
  140. ~~~~~~~~~~~~
  141. Here you can switch a drive off by setting HD_StatHDx to 0xFFFF.
  142.  
  143. hd_Quit         equ     $05
  144. ~~~~~~~
  145. This tries to terminate HDOff.  If the reply has HD_Cmd=hd_Die quitting was
  146. successfull, if not not :)
  147.  
  148. hd_ForceQuit    equ     $06
  149. ~~~~~~~~~~~~
  150. The  same as hd_Quit, but using the force option (can`t fail), and you will
  151. get a reply.  NOTE:  read the warning about the FORCE-option in the doc!
  152.  
  153. hd_Die          equ     -1
  154. ~~~~~~
  155. NOTE:  you can _only_ recive this!  If you get this Message, HDOff has been
  156. terminated and you must stop using the port any longer!  (You will only get
  157. this if you subscribed).
  158.  
  159. hd_Failure      equ     -2
  160. ~~~~~~~~~~
  161. NOTE:   you  can  only recive this, too!  It`s returned by hd_Subscribe and
  162. hd_Unsubscribe on error.
  163.  
  164. hd_HDoffVersion    equ    $07
  165. ~~~~~~~~~~~~~~~
  166. This  one  gives you a pointer to HDOff`s versionstring in HD_PortVer back,
  167. e.g.  "$VER:  HDOff x.x (x.x.x)". NOTE: Of cause read only!
  168.  
  169. hd_QueryCtrl    equ     $08
  170. ~~~~~~~~~~~~
  171. This  nice thing will tell you wich controller you`re on.  The result is in
  172. HD_StatHD0.   A  0  means  A600/A1200, a 1 A4000, and new for 1.40, 2 means
  173. CD32 ProModule.
  174.  
  175. EXAMPLE
  176.  
  177. If  you  want, have a look in GetStats.c.  It shows you how to deal with an
  178. exec port and how to use the hd_GetStats and hd_HDoffVersion commands.
  179.  
  180. HISTORY
  181.     v1.0  - extremly quick&dirty docs about the port
  182.     v1.1  - Reformated the text and added the C informations
  183.     v1.11 - Adapted for HDOff 1.36
  184.         v1.12 - Adapted for HDOff 1.37
  185.         v1.2  - Adapted for HDOff 1.40
  186.